docs(automation): define the Coven-to-Psyche automation adapter contract - #5

Summary

Spec/design artifact for the Psyche adapter by which a Coven automation occurrence invokes Psyche for multi-step, multi-lane, approval-aware orchestration without transferring schedule, occurrence, or run authority into Psyche. Spec-only change: no runtime code paths are touched.

What lands in this PR:

• docs/AUTOMATION-ADAPTER.md — the design document: canonical boundary (Coven owns / Psyche owns / neither), semantic separation of the seven identifier layers (occurrence, run, attempt, invocation, task/lane/lease, worker session, artifacts) with one ownership source each, invocation/event/result/error contracts, state machines that reuse the already-frozen GraphState/NodeState/CancellationState vocabularies (crates/psyche-core/src/contracts/graph.rs, crates/psyche-core/src/contracts/execution.rs), adoption/idempotency/conflict rules reusing the store's immediate-transaction + canonical-bytes replay semantics (crates/psyche-store/src/execution_bindings.rs), cancellation/timeout/restart/recovery semantics, changefeed/backpressure rules, the PsycheAutomationPort seam (transport-neutral, mirroring CovenPort idioms), twenty golden scenarios mapped to proposed suites, a verification/canary plan, and five maintainer decisions with alternatives considered.
• Four JSON Schema (draft 2020-12) contracts under docs/schemas/automation-adapter/: psyche.automation_invocation.v1, psyche.automation_event.v1, psyche.automation_result.v1, psyche.automation_error.v1 — strict (additionalProperties: false everywhere), safe-integer and 1 MiB bounds matching crates/psyche-core/src/contracts/mod.rs, digest forms matching crates/psyche-core/src/digest.rs.
• Canonical golden examples with recomputed SHA-256 digests: invocation envelope (invocation_digest = sha256 over the canonical invocation content, the AdoptionRequest envelope precedent), first chained event (chain rooted at the adopted invocation_digest), terminal result (result_digest), and the referenced orchestration brief.
• A bead packet (§20 of the doc) for the tracker owner; bead state was deliberately not modified.

Key design stances (details + alternatives in the doc):

• One invocation_id is the idempotency key; the digest over its canonical bytes detects same-key/different-bytes conflicts. Timeout after possible adoption reconciles by lookup, never by a new key.
• The adapter never owns schedules: automation.definition_* fields are pinned evidence, not executable policy. No Psyche API creates or edits automation schedules.
• Familiar identity and Threads authority are consumed, pinned, and inherited-or-narrowed per lane — never broadened; refusals (binding_mismatch, principal_mismatch, authority_expired, …) are durable, payload-light evidence.
• ExecutionBinding (att_) is deliberately not reused for the automation layers.

Issue

Refs OpenCoven#18

Test plan

• Local: all four JSON Schemas parse; goldens and schemas structurally validated with a local draft-2020-12 subset validator (type/const/enum/pattern/bounds/required/additionalProperties/$ref)
• Local: golden examples verified as canonical bytes (RFC 8785 round-trip); invocation_digest, result_digest, and event payload_digest recomputed and match; brief digest binds the shipped brief bytes; result echoes the exact invocation correlation; exercised runtime capabilities ⊆ runtime.required_capabilities
• Local negative probes: unknown schema major, additional field, bad ULID prefix, relative workspace path, malformed digest, non-terminal status — all rejected
• All code paths cited in the design document verified to exist at this SHA
• cargo fmt / clippy --workspace --all-targets -- -D warnings / cargo test --workspace --locked — deferred to CI (docs-only change; no Rust or manifest touched)

Vehicle note: opened in the fork CompleteDotTech/psyche as the CI vehicle — this token cannot write to OpenCoven/psyche. Re-target upstream once write access is restored. Refs OpenCoven#18.

CI note: no CI exists on this fork vehicle — repos/CompleteDotTech/psyche/commits/<head>/check-runs returns total_count: 0, the Actions settings are enabled but zero workflows have ever registered on the fork (fresh forks require a one-time UI enablement with no API equivalent), so no pull_request run was created for this PR. The upstream ci.yml gates (fmt, clippy, locked workspace tests, G2 suites, cargo-deny, gitleaks, npm wrapper legs) will run when this branch is re-targeted to OpenCoven/psyche.